Inside Macintosh: Open Transport /

Chapter 6 - Configuration Management

About Provider Configurations

Before you can open a provider, you must first tell Open Transport how to configure it with the protocol and options you want the provider to use. To do this, you pass a string to a function (OTCreateConfiguration) that creates a configuration structure (of data type OTConfiguration) describing the service you want.

The configuration string can be the name of a single protocol, such as "adsp", "tcp", or "dnr," or it can be a full comma-separated list of protocol and port names, with option values specified in parentheses after the name of the protocol to which they apply. For instance,

"adsp,ddp,ltlkB" 

describes an AppleTalk Data Stream Protocol (ADSP) endpoint provider using the Datagram Delivery Protocol (DDP) and with LocalTalk link access provided through the default port (the LocalTalk B printer port).

Open Transport has internally defined defaults for how protocols can be layered upon each other. If you give Open Transport a single protocol name, it checks its defaults to determine which lower layers are missing. Thus, the shorter string

"adsp" 

also describes an identical ADSP endpoint provider. Likewise, if you skip a protocol layer in the string, Open Transport uses its defaults to try to complete it. For instance, the specification "tcp, enet" is incomplete because the Transmission Control Protocol (TCP) does not have direct access to Ethernet, and so Open Transport puts the default Internet Protocol (IP) between TCP and Ethernet.

You can also specify an option as part of the configuration string. To do this, you need to know which protocols use which options and how to translate the option's constant name, given in the header files, into a string that the configuration functions can parse. See the TCP/IP and AppleTalk chapters for lists of their procotol-specific options and their equivalent string values, but for a simple example,

"adsp,ddp(Checksum=1)" 

describes an ADSP endpoint provider with the DDP checksum option enabled.

If you want to identify a particular port in the configuration string, you use the port name to do so (described in the next section). More typically, however, you leave this value blank--for example, using only "adsp" or "adsp, ddp," which configures the provider with whatever port is specified in the associated control panel.

Most protocols have a hardcoded string value that you can use to configure providers. For example, DDP uses "ddp" and ADSP uses "adsp." There are also constants that identify each protocol, such as kDDPName and kADSPName. For a complete list of the AppleTalk constant-string equivalents, see the chapter "Introduction to AppleTalk" in this book. For a TCP/IP service provider, you can use the constant kDefaultInternetServicesPath; there is no hardcoded equivalent.

You can use the constant or the hardcoded value to create providers that do not use options and that adhere to the default procotol layering. For example, to configure a fairly straightforward DDP endpoint, you could use either of the following lines of code:

OTOpenEndpoint(OTCreateConfiguration("ddp"), 0, NULL, &err) 
OTOpenEndpoint(OTCreateConfiguration(kDDPName), 0, NULL, &err);

To configure more complex providers, it is easier to use the hardcoded strings. Using the constant can be confusing, as compared in the following lines of code:

OTOpenEndpoint(OTCreateConfiguration
      ("adsp(EnableEOM=1),ddp,ltlkB"), 0, NULL, &err) 
OTOpenEndpoint(OTCreateConfiguration
      (kADSPName"(EnableEOM=1),"kDDPName",ltlkB"), 0, NULL, &err);

Note

The OTCreateConfiguration function returns a pointer to the configuration structure it creates. You pass this pointer as a parameter to the open-provider functions such as the OTOpenEndpoint or OTOpenMapper functions (discussed in the chapters "Endpoints" and Mappers" in this book).